/**
 *   _                                                          _   
 *  | | ____ _ _ __ _ __ ___   __ _  ___           _ __ ___ ___| |_ 
 *  | |/ / _` | '__| '_ ` _ \ / _` |/ __|  _____  | '__/ _ | __| __|
 *  |   < (_| | |  | | | | | | (_| | (__  |_____| | | |  __|__ \ |_ 
 *  |_|\_\__,_|_|  |_| |_| |_|\__,_|\___|         |_|  \___|___/\__|
 *         
 *  Copyright  2011 Kondra, Inc. 
 * 
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at:
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

package com.kondra.karmac.rest
{
   /**
    * Interface for implementing service endpoints.
    * 
    * @author Jared Kaplan
    */ 
   public interface IServiceEndpoint
   {
      /**
       * Returns the name of this service endpoint, used by the service manager
       * to register itselft in the service map.
       */ 
      function getName() : String;
         
      /**
       * Returns the service data factory associated with this endpoint.
       */ 
      function getServiceDataFactory() : IServiceDataFactory;
      
      /**
       * Returns the specified result format of this endpoint.
       */ 
      function getResultFormat() : String;
      
      /**
       * Returns an <code>IServiceTask</code> object that can be invoked to
       * call the method specied by this service endpoint.
       * 
       * @param data             Values that will be sent to the service with the request
       * @param completeHandler  The function that will be called when the request
       *                         is complete
       * @param errorHandler     The function that will be called then request is not
       *                         completed due to an error
       * @param progressHandler  The function that will be called during the request
       *                         as data is loaded from the service
       */  
      function createServiceTask( data:Object = null, completeHandler:Function = null, 
                                  errorHandler:Function = null, progressHandler:Function = null ) : IServiceTask;
      
      /**
       * Invokes the service method and returns the associated <code>IServiceTask</code>
       * object for the request.
       * 
       * @param data             Values that will be sent to the service with the request
       * @param completeHandler  The function that will be called when the request
       *                         is complete
       * @param errorHandler     The function that will be called then request is not
       *                         completed due to an error
       * @param progressHandler  The function that will be called during the request
       *                         as data is loaded from the service
       */
      function invoke( data:Object = null, completeHandler:Function = null, 
                       errorHandler:Function = null, progressHandler:Function = null ) : IServiceTask;
   }
}